MSGCTL
Section: System Calls (2)
Index
Return to Main Contents
BSD mandoc
NetBSD
NAME
msgctl
- message control operations
SYNOPSIS
Fd #include <sys/types.h>
Fd #include <sys/ipc.h>
Fd #include <sys/msg.h>
Ft int
Fn msgctl int msqid int cmd struct msqid_ds *buf
DESCRIPTION
The
Fn msgctl
system call performs some control operations on the message queue specified
by
Fa msqid .
Each message queue has a data structure associated with it, parts of which
may be altered by
Fn msgctl
and parts of which determine the actions of
Fn msgctl .
The data structure is defined in
Aq Pa sys/msg.h
and contains (amongst others) the following members:
struct msqid_ds {
struct ipc_perm msg_perm; /* msg queue permission bits */
u_long msg_cbytes; /* # of bytes in use on the queue */
u_long msg_qnum; /* # of msgs in the queue */
u_long msg_qbytes; /* max # of bytes on the queue */
pid_t msg_lspid; /* pid of last msgsnd() */
pid_t msg_lrpid; /* pid of last msgrcv() */
time_t msg_stime; /* time of last msgsnd() */
time_t msg_rtime; /* time of last msgrcv() */
time_t msg_ctime; /* time of last msgctl() */
};
The
Bf -literal
ipc_perm
Ef structure used inside the
Bf -literal
shmid_ds
Ef structure is defined in
Aq Pa sys/ipc.h
and looks like this:
struct ipc_perm {
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
ushort uid; /* user id */
ushort gid; /* group id */
ushort mode; /* permission (9 bits, see chmod(2)) */
ushort seq; /* sequence # (to generate unique id) */
key_t key; /* user specified msg/sem/shm key */
};
The operation to be performed by
Fn msgctl
is specified in
Fa cmd
and is one of:
- IPC_STAT
-
Gather information about the message queue and place it in the
structure pointed to by
Fa buf .
- IPC_SET
-
Set the value of the
msg_perm.uid
msg_perm.gid
msg_perm.mode
and
msg_qbytes
fields in the structure associated with
Fa msqid .
The values are taken from the corresponding fields in the structure
pointed to by
Fa buf .
This operation can only be executed by the super-user, or a process that
has an effective user id equal to either
msg_perm.cuid
or
msg_perm.uid
in the data structure associated with the message queue.
The value of
msg_qbytes
can only be increased by the super-user. Values for
msg_qbytes
that exceed the system limit (MSGMNB from
Aq Pa sys/msg.h )
are silently truncated to that limit.
- IPC_RMID
-
Remove the message queue specified by
Fa msqid
and destroy the data associated with it. Only the super-user or a process
with an effective uid equal to the
msg_perm.cuid
or
msg_perm.uid
values in the data structure associated with the queue can do this.
The permission to read from or write to a message queue (see
msgsnd(2)
and
msgrcv(2))
is determined by the
msg_perm.mode
field in the same way as is
done with files (see
chmod(2)),
but the effective uid can match either the
msg_perm.cuid
field or the
msg_perm.uid
field, and the
effective gid can match either
msg_perm.cgid
or
msg_perm.gid
RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, -1 is
returned and the global variable
errno
is set to indicate the error.
ERRORS
Fn msgctl
will fail if:
- Bq Er EPERM
-
Fa cmd
is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
the effective uid match either the
msg_perm.uid
or
msg_perm.cuid
fields of the data structure associated with the message queue.
An attempt is made to increase the value of
msg_qbytes
through IPC_SET
but the caller is not the super-user.
- Bq Er EACCESS
-
The command is IPC_STAT
and the caller has no read permission for this message queue.
- Bq Er EINVAL
-
Fa msqid
is not a valid message queue identifier.
cmd
is not a valid command.
- Bq Er EFAULT
-
Fa buf
specifies an invalid address.
SEE ALSO
msgsnd(2),
msgrcv(2),
msgget(2)
HISTORY
Message queues appeared in the first release of AT&T Unix System V.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUES
-
- ERRORS
-
- SEE ALSO
-
- HISTORY
-
This document was created by
man2html,
using the manual pages.
Time: 16:28:59 GMT, April 18, 2022